The basics of the Project Editor
This section will help you to get accustomed with the Project Editor. This "training" session requires the availability of a couple of *.MD1 files in the project directory. You can find some of them in the tutorial directory: I suggest you to copy them into the project directory.

Note: To assign the project directory, open the working directories window by clicking on the button on the Graphic Editor tool bar.

Note: A *.MD1 file is a file resulting from the compilation of a simple assembly.

OK. So, I assume it didn't take you a long time to do that. Make sure the model you are working on is declared as a master project (File/Rename menu option, master project option checked). If it is not, please do it. Launch the Project Editor by clicking on the project editor button on the tool bar or by selecting the File/Model Editor menu option or by hitting the F10 key. The Project Editor window is now displayed on the screen. It displays the project code page.


Tip: You can also open the Project Editor from the Model Tree Editor window by clicking on the master project button.

The Project Editor window is composed of:

In the instruction window, each instruction is made up of three fields (label, instruction code, data). A big red dot in the margin indicates the currently selected instruction. Blue dots in the margin spot undefined or illegal jumps. The total number of instructions and the selected instruction # are displayed in the left part of the status bar. The rigth part of it displays warning or error messages.

Clicking on an instruction selects it. If you click on an instruction and then click on another one while pressing the shift key, you select several instructions.

At the moment, the instruction list is pretty short: a few lines. It is the project code page. You should see the following instructions (I assume you called the assembly MYASSY and the project MYPROJ:
MYPROJ  PROJECT          demo project
        MODEL SIZE       50 ft
        INTERNAL VIEW    no view
MYASSY  INSERT MAIN ASSY my assembly
        END OF PROJECT   caution : this is not a return instruction


Insert an instruction

Click once on the INSERT MAIN ASSY instruction code. The field you clicked on is highlighted. Now click on the insert button on the tool bar. An instruction selection panel is displayed in an input window. The following options are available:


Tip: To get more information on the Project Editor instructions, have a look at the Project Editor reference guide.

Tip: The AD2K2 Model Editor allows you to insert comments inside the code. To do that, insert a COMMENT instruction and then double-click on the data field of it. An input window is launched which allows you to enter a comment.

Select an instruction by clicking on the related radio-button: let's go for a RETURN for instance. Validate: a RETURN instruction is inserted into the list. Not happy with that RETURN instruction ? Double-click on the code field of it: the instruction selection panel is displayed again and you can modify your selection.

Note: If you select the IF SIZE instruction, a pair of instructions is inserted. That's a special feature of the IF SIZE instruction: it is associated to a GAUGE to form a combined pair of instructions. You cannot insert one without inserting the other one. You cannot delete one without deleting the other one. You cannot select one without selecting the other one. You cannot insert another instruction between the two of them.


Playing with the instructions...

Let's take a few minutes to play with the instructions in the Project Editor. Select again the instruction you have just created by clicking on it. Then click on the delete button on the tool bar. The selected instruction is deleted. Select now the INSERT MAIN ASSY instruction and click on the delete button. Nothing happens, except a warning message in the status bar. Some instructions cannot be deleted:

Click now on the instruction code field of the INSERT MAIN ASSY instruction. Click then on the cycle button at the left on the tool bar. The instruction is changed to become a CALL MAIN ASSY instruction. Click again on this button : the former INSERT MAIN ASSY instruction is retrieved. Try to do that with a RETURN instruction : nothing happens. This cycle command only applies to the following instructions: Let us go back to the Project Editor. Insert a few instructions in the list. Select one of the instruction you have created. Click on the Move To button on the tool bar. The cursor is changed : you are now in the move to mode. Click on another instruction. The previously selected instruction is inserted before the instruction you just clicked on.

Try to do that with the first instruction: nothing happens and a warning message is displayed in the status bar. Try now to to delete this instruction by clicking on the delete button: nothing happens and another warning message is displayed in the status bar. In the Project Editor, there are different categories of instructions:

Calling and inserting assemblies

The project code page allows you to insert assemblies in the model. There are three instructions to do that:

The two first intructions can be inserted in the code page with the insert button of the tool bar. The third one is a basic non-modifiable instruction of the code list. To assign an assembly to one of these instructions, double-click on the data field of the instruction. An assembly selection window is opened which displays all the compiled assemblies (i.e. *.MD1 files) available in the project directory. Select the assembly you want and validate. The instruction code is updated withe the assembly name in its data field. If you are not happy with your selection, you can double-click again on the data field to modify it.

Tip: When there is no assembly assigned to the INTERNAL VIEW instruction, the instruction data field is set to no view. In that case, the internal view command of FS will have no effect.

What is the difference between a CALL instruction and an INSERT instruction ?
You must think of the assembly as a piece of code which is ended by a RETURN instruction. When it is called by a CALL instruction (CALL MAIN ASSY or CALL ASSEMBLY), the FS viewer acts as described just before:
  • the FS viewer puts the address of the CALL ASSEMBLY instruction on the top of the RETURN stack,
  • it goes to the specified address (which is the address of the assembly),
  • it executes the assembly code (which means it draws the assembly),
  • then it goes back to the instruction immediately following the CALL ASSEMBLY instruction and removes the address of it from the RETURN stack.
When the FS viewer loads an INSERT instruction (INSERT MAIN ASSY or INSERT ASSEMBLY), it is acting as if it was a jump instruction. As the assembly code is ended by a RETURN instruction, once it is executed the FS viewer retrieves the address on the top of the RETURN stack which is NOT the address of the INSERT instruction. What happens ? If the stack is empty, the model viewing process is terminated. If it is not, the FS viewer simply goes to the retrieved address...

Jump addresses and labels

The CALL MODULE instruction, the GO TO LABEL and the IF SIZE instruction require a destination address. The CALL MODULE instruction is a kind of subroutine call, the GO TO LABEL instruction is an unconditional jump and the IF SIZE instruction is a test. How do we assign a destination address to this kind of instruction ?

Let us insert a couple of instructions into the assembly code page. For instance, insert the following sequence in code page:
MYPROJ  PROJECT          demo project
        MODEL SIZE       50 ft
        INTERNAL VIEW    no view
        CALL MODULE      ?
        RETURN
        COMMENT          ?
        INSERT ASSEMBLY  ?
        GO TO LABEL      ?
        CALL ASSEMBLY    ?
        RETURN

MYASSY  INSERT MAIN ASSY my assembly
        END OF PROJECT   caution : this is not a return instruction

Tip: Blue dots are painted on the left of some instructions: they mean that these instructions are unassigned.


The meaning of this sequence makes no sense but it does not matter, it is just a way to make you understand how AD2K2 deals with labels and destination addresses.

Double-click on the data field of the first CALL MODULE instruction in the list. The cursor appearance changes: it was a small arrow, it is now a finger pointing upwards. The Project Editor is in the addressing mode. To exit this mode and resume the normal mode, you must point at an existing label, or point at a non-labeled instruction, or click on the resume button on the tool bar. At the moment, there is no predefined label and we have no reason to resume the normal mode either: I suggest you to click on the INSERT ASSEMBLY instruction. The cursor goes back to its normal appearance and a label input window is displayed. You must enter an alphanumeric label (8 characters maximum): let's go for MYLABEL. Validate by clicking on the OK button.

MYLABEL looks good, but what if we need other labels ? I suggest we turn it into MYLABEL1. To do that, double-click on the label field of the INSERT ASSEMBLY instruction we have just labeled MYLABEL. The label input window is displayed again, with MYLABEL in the input field. Turn it into MYLABEL1 and validate by clicking on the OK button. Have a look at the CALL MODULE instruction at the beginnig of the list: it is now pointing at MYLABEL1. AD2K2 keeps dynamics links between the destination addresses and the labels of the instructions which are pointed at.

Double-click now on the label field of the CALL ASSEMBLY instruction and assign it the MYLABEL2 label. Go back to the first CALL MODULE instruction and double-click on its data field (it is presently pointing at MYLABEL1). AD2K2 goes into the addressing mode and the finger cursor is displayed. Click on the MYLABEL2 label. Look at the result: the CALL MODULE data field is now updated and the destination address is MYLABEL2 instead of MYLABEL1.

One more experiment ? Double-click on the GO TO LABEL instruction data field. You are back in the addressing mode. Click on the INSERT MAIN ASSY instruction. The GO TO LABEL instruction is now addressing the MYASSY label.

Compilation

Once you are finished with the project code page, you need to compile it. Click on the compile button of the tool bar to do that.



copyright Hervé Devred, 2003